FST-Viewer V3.0 Readme


Inhalt

1. Was ist FST und der FST-Viewer?
2. Das Programm

3. Die FST-Technologie
3.1 Die Syntax der FST-Dateien
3.2 Die Symbolik
3.3 Befehlsreferenz
3.4 SELECT
3.5 Skript-Befehle

4. Befehlszeile und Dateianbindung

5. Fehlermeldungen und FAQ

6. Bekannte Bugs

7. Versions-Geschichte

8. Copyright


1. WAS IST FST UND DER FST-VIEWER?

FST = "Formatted Story-File" = Formartiere Geschichts-Datei

Diese Technologie erlaubt ablaufgesteuerte Texte darstellen zu knnen,
wobei der Benutzer entscheidet, wo er wie weitergehen will.

Der Viewer gestattet liest die FST-Dateien und gibt die,
entsprechend der FST-Technik aus.


2. DAS PROGRAMM

Das Programm ffnet eine FST-Datei und liest den ersten Sektor.

"Datei-ffnen" ffnet eine andere FST-Datei
"Datei-Schlieen" schliet die aktuelle Datei
"Datei-Ende" schliet den Viewer

"Info-Dateiinfo" gibt die Dateiinformationen an, wie Autor.
"Info-Programminfo" gibt Informationen ber den Viewer selbst an.

"Navigation-Anfang" zeigt wieder die Seite vom ersten Sektor an.
"Navigation-Gehe zu..." ffnet ein Fenster, wo jeder Sektor angewhlt werden kann.

"System-Version 1.0" verwendet die Version 1.0 der FST-Technologie.
	Diese Version hat einen reduzierten Bereich von Befehlen, arbeitet aber, im
	Zweifelsfall, schneller.
"System-Version 2.0" verwendet die Version 2.0 der FST-Technologie.
	Das ist neuste Version der FST-Technologie.
	Allerdings ist diese etwas anspruchsvoller als Version 1.0 und
	weil der Befehlszeichensatz grer ist, sind bestimmte Zeichenkombinationen
	nicht mehr zulssig!

Benutzen Sie das Keyboard, um SELECT-Statements anzuwhlen.


3. DIE FST-TECHNOLOGIE

3.1 Die Syntax der FST-Dateien

Jede FST-Datei kann mit einem gewhnlichen Text-Editor
bearbeitet werden.

Zwingend ist folgender Header und Syntax:

(Version 1.0)

FST [Version]
<DATA>
[Autorname]
[Version]
[Modus]
<FONT>
[Schrift Text]
[Schrift Titel]
[Schrift Sprache]
[Schrift Auswahl]
[Schrift Auswahl-Titel]
[Schrift Kommentar]
<TITLE>
[Titel]
<BODY>
$$[Startsektor]
...
<END>

(ab Version 2.0)

FST [Version]
<DATA>
[Autorname]
[Version]
[Modus]
<FONT>
[Schrift Text]
[Schrift Titel]
[Schrift Sprache]
[Schrift Auswahl]
[Schrift Auswahl-Titel]
[Schrift Kommentar]
<UFONT>
[Eigene Schriften]
...
<CONTROLS>
useFormatSpeech
useFormatComment
<TITLE>
[Titel]
<BODY>
$$[Startsektor]
...
<END>


Alle Angaben in []-Klammern sind durch die entsprechenden Werte zu
ersetzen!
Die [] sind dann wegzulassen!

Schriften erfordern den Syntax:
Name/Gre/Attribute/Farbe

Name = Glter Schriftartenname
Gre = Schriftgrad
Attribute = Kombination aus B (Fett), I (Kursiv) und/oder U (Unterstrichen)
Farbe = BGR-Hexwert (RGB-invertiert)

(ab Version 2.0)
Es knnen beliebige eigene Schriftarten (<UFONT>) definiert werden.
Auch die Anzahl ist unbegrenzt.
Fehlt der Bereich oder ist der Bereich leer, werden ALLE Steuerzeichen der
Formatierungs-Klasse, also "$" und "%", ignoriert!

"useFormatSpeech" entscheidet ob wrtliche Reden, also nicht-Kommentar oder SELECT-Texte
	in Anfhrungsstrichen <"...">, durch die Schrift "Sprache" hervorgehoben werden.
	Wenn "useFormatSpeech=1" angegeben oder der Punkt gnzlich fehlt,
	um die Formatierung zu aktivieren. "useFormatSpeech=0" deaktiviert die Formatierung
	und lsst wrtliche Reden.
"useFormatComment" entscheidet ob Kommentare hervorgehoben werden.
	Kommentare sind Texte, auch wrtliche Reden, die von runden Klammern <(...)>
	eingeschlossen sind. Sie werden mit der Schrift "Kommentar" formatiert.
	Es gelten dieselben Regeln fr das aktivieren bzw deaktivieren, wie bei
	"useFormatSpeech".


3.2 Die Symbolik

<...> = Befehlswort
$$... = Markierung
//... = Kommentar (ist im Viewer unsichtbar!)
... = Schlsselwort (siehe Befehelsreferenz)

Alle Symbole sollten am Zeilenanfang stehen!
Symbole, die in der Mitte einer Zeile auftauchen, werden zwar beachtet, doch
die ggf nachfolgenden Werte knnten fehlinterpretiert werden!

3.3 Befehlsreferenz

In einem Sektor (einen Text-Abschnitt im Krper der FST-Datei, der
zu einem Markierung gehrt) drfen folgende Schlsselwrter verwendet werden:

TITLE [Titel]
Hebt den Text "Titel" besonders vor.
Nimmt eine ganze Zeile ein und darf nur am Zeilenanfang stehen!

"..."
Markiert eine Wrtliche Rede.

(...)
Markiert einen sichtbaren Kommentar

SELECT, POS und &
siehe 3.4!


(ab Version 2.0)
$[Nummer]
Fordert den Viewer auf, eine selbstdefinierte Schrift zu verwenden.
[Nummer] ist optional.
Es gilt:
Die Indizes der selbstdefinierten Schriften beginnen bei "1" und zhlen aufwrts.
Wird die "Nummer" in der Liste gefunden beginnt ab diesem Steuerzeichen die Formatierung.
Wenn nicht, wird das Steuerzeichen ignoriert.
Wird keine "Nummer" angegeben, so wird die standartmig die Schrift #1 verwendet.

Diese Formatierung bleibt ber Abstze, wrtliche Reden, SELECTS und Kommentare erhalten.
Nach einem Titel oder am beginn eines neuen Sektors, wird wieder die standart-Schrift
verwendet.

%
Normalisiert die Schrift wieder zum Standart.


3.4 SELECT

Dieser Statement-Block gestattet die Ablaufsteuerung.

Folgender Syntax ist einzuhalten:

SELECT [Select-Titel]
POS [Pos-Name] ?= [Ziel] #[Taste]
POS ...
...
&

[Select-Titel] umfasst den Titel oder Aufforderung fr die
Auswahl.

[Pos-Name] bezeichnet den Name dieser Auswahlmglichkeit.

[Ziel] muss eine gltige Markierung sein (ohne $$-Prfix) die
angesteuert werden muss.

[Taste] eine Buchstabentaste (in Grobuchstaben) die dieser
Auswahl zugewiesen werden soll.
Pro Sektor mssen die Tasten eindeutig sein, ber die FST-Datei
drfen sich die Tasten widerholen!

Das Symbol "&" schliet die Auswahl.

Jede Auswahl darf beliebig viele POS-Statements haben.

Soll eine Position ungebunden bleiben, also ohne Ziel und Taste,
ist folgender Syntax glig:
POS [Pos-Name] ?= .


3.5 Skript-Befehle
(ab Version 3.0)

Alternativ zu einem Sprungziel (s. [Ziel] oben), kann in einer POS-Klausel ein
Skript-Befehl angegeben werden, der ausgefhrt wird, wenn der
der POS-Event ausgefhrt wird.

Anstatt ein gewhnliches Ziel anzugeben, gibt es folgende reservierte
Begriffe:
%%OPEN <[Dateiname]>:
	Schliet die akuelle FST-Datei und ffnet die unter [Dateiname]
	angegebene FST-Datei.
	ACHTUNG: Die aktuelle Position geht dabei verloren!
%%CLOSE:
	Schliet die aktuelle FST-Datei.
%%END:
	Beendet sofort den Viewer.

Beispiel:
SELECT Beenden?
POS Ja ?= %%END #J
POS Nein ?= Init #N
&


4. Befehlszeile und Dateianbindung

Der FST-Viewer akzeptiert auf der Kommandozeile eine beliebige
FST-Datei.

Daher ist er auch dazu geeignet als View-Programm zu fungieren,
als Standart-Reaktion auf dem ffnen-Befehl von FST-Dateien.

Ordneroptionen->Dateitypen->Neuer Typ->
*.fst->Vorgang "ffnen"->Anwendung "FST-Viewer.exe" %1


5. Fehlermeldungen und FAQ

a) Fehlermeldungen

Fehlermeldung:
	"Invalid File Type!"
Ursache:
	Ungltige FST-Datei
Lsung:
	Sie versuchen entweder eine Datei zu laden, die keine FST-Datei ist, oder
	der Inhalt dieser FST-Datei ist ungltig.
	ffnen Sie die Datei in einem Editor und berprfen Sie, ob in der ersten Zeile
	die Buchstaben "FST" stehen!

Fehlemeldung:
	"SELECT-Broken!"
Ursache:
	SELECT-Block wurde definiert, wird aber nicht durch "&" abgeschlossen.
Lsung:
	Suchen Sie nach dem/den SELECT-Block/Blcken, denen dieses Zeichen fehlt und ergnzen
	diese um diese Zeichen.
	Beachten Sie auch die Schreibweise der POS-Statements! (Grosschreibung beachten!)

Fehlermeldung:
	"Fields in Data-Header invalid!"
Ursache:
	Im <DATA>-Block befinden sich unter "Version" bzw "Modus" Eintrge die keine Ziffern sind,
	oder nicht in solche umgewandelt werden knnen.
Lsung:
	berprfen Sie den Block.
	Denken Sie dran: 1. Eintrag: Name vom Autor (Beliebige Zeichenkette)
		2. Eintrag: Version im Format X,Y (z.B. 1,0)
		3. Eintrag: Modusauswahl (eine Ziffer)

Fehlermeldung:
	"Version unreadable!"
Ursache:
	Es wurde eine Kennzeichnung fr die FST-Version angegeben, doch sie ist ungltig.
Lsung:
	berprfen Sie die Versionskennziffer.
	Gltig ist folgender Statement: "FST VX,Y" (X = Hauptversion; Y = Nebenversion)

Fehlermeldung:
	"Version incompartible! FST-File is newer than viewer!"
Ursache:
	Es wurde eine neuere Version in der FST-Datei angegeben, als der Viewer untersttzt.
Lsung(en):
	1. Versuchen Sie die Datei mit einer neueren Version zu ffnen.
	(System -> Version 2.0; System -> Version 3.0)
	2. Laden Sie sich die neuste Version es Viewers runter.
	3. Kontaktieren Sie den Entwickler

Fehlermeldung:
	"Control-Section >UseFormatSpeech< corrupted!"
	"Control-Section >UseFormatComment< corrupted!"
Ursache:
	Die betreffenden Felder ("UseFormatSpeech" bzw "UseFormatComment") wurden zwar angegeben,
	doch der Syntax ist fehlerhaft.
Lsung:
	berprfen Sie den Syntax dieser Felder.
	Gltig ist:
	[Feldname]=1 (zum aktivieren) bzw [Feldname]=0 (zum deaktivieren)

Fehlermeldung:
	"FST-Script Error: Filename-Delimeters invalid!"
Ursache:
	Im Skript-Befehl "%%OPEN" wurde auf eine ungltige Weise der Dateiname bergeben.
Lsung:
	berprfen Sie ihre "%%OPEN"-Befehle
	Der Dateiname muss immer unmittelbar mit einem "<" beginnen und mit einem
	">" abgeschlossen werden.

Fehlermeldung:
	"FST-Skript: Linked File ([Dateiname]) cannot be found!"
Ursache:
	Sie haben im Skriptbefehl "%%OPEN" eine Datei angegeben, die das System nicht finden kann.
Lsung:
	berprfen sie Pfad und Dateiname der Zieldatei.

Fehlermeldung:
	"System Error! FST-File (V3.0) is corrupt!"
Ursache:
	Schwerer FST-Viewer System Fehler!
Lsung:
	Sie haben eine eine FST-Datei nicht als Version 3.0 geffnet, versuchen aber dann
	ber den "System"-Menpunkt diese als solche zu verwenden.
	Schlieen Sie den Viewer und ffnen Sie die Datei korrekt!


b) FAQ

F: Ich habe eine FST-Datei, aber der Viewer zeigt nichts an. Warum?
A: berprfen Sie...
...ob der Tag <BODY> existiert und richtig geschrieben ist
...ob die Standart-Schrift fr Normal-Text (1. Feld nach <FONT>) gltig ist und die
	Farbe nicht schwarz ist (=000000)
...ob mindestens ein Sektor-Marker exisitert und Ihr Text unter diesem Marker zu finden ist
...ob Ihr Text nicht mit einem "//" beginnt!

F: Ich habe einen SELECT-Block, aber im Viewer kann ich bestimmte Aufwahlpunkte nich anwhlen,
	bzw der Viewer reagiert nicht drauf, wenn ich die Taste drcke. Warum?
A: berprfen Sie den SELECT-Block und seine POS-Statements!
	Stellen Sie sicher, dass jeder POS-Statement aus einem Titel, einem Sprungziel und
	Taste besteht. (POS [Titel] ?= [ZIEL] #[TASTE])

	Stellen  Sie auerdem Sicher, dass Ihr Sprungziel exisitert! (Gro/Kleinschreibung wird
	bercksichtigt!)

	Wenn Sie als Ziel einen Punkt "." angegeben haben, fhrt dieser Link nirgens hin!

F: Steuerzeichen, Skriptbefehle oder gar ganze Tags werden ignoriert! Was soll ich tun?
A: berprfen Sie die Schreibweise!
	Tags stehen immer in einer eigenen Zeile und werden von <>-Klammern eingeschlossen.
	Skriptbefehle drfen nur in der "Ziel"-Klausel eines POS-Statements stehen und
	mssen mit einem "%%"-Zeichen beginnen
	Steuerzeichen, wie Format-Bezeichner oder Marker haben einen festen Syntax.
	Bedenken Sie:
		"$$" = Marker (darf nur am anfang und in einer eigenen Zeile stehen!)
		"$", "%" = Format-Bezeichner

F: Die Formatierung von Kommentaren und/oder wrtl. Rede ist ganz wirr!
	(wrtl. Rede wird bei gewhnlichen Text und andersrum angezeigt.) Was ist da los?
A: Vermutlich haben Sie irgendwo im Text eine schlieende ")" oder """ vergessen.
	berprfen Sie ihren Text auf diesen Fehler.
	Sie knnen den Fehler eingrenzen, indem Sie die FST-Datei durchschauen, und darauf achten,
	wann der Fehler erstmals auftritt. Auf dieser Seite oder auf eine der vorhergehenden,
	muss der Fehler sein!

F: Der Befehl "Navigation -> Gehe Zu..." ist inaktiv. Warum?
A: Sie haben die reduzierte Version des FST-Viewers.
	Das ist absicht so!

F: Wieso sehe ich (die) Steuerzeichen im Text?
A: berprfen Sie die entsprechenden stellen.
	Werden die Zeichen aktiv bercksichtigt?
	Ja: Fehler vom Viewer! Kontaktieren Sie den Entwickler!
	Nein: Entweder hat das Steuerzeichen an dieser Stelle keine Wirkung
		(z.B. "&" ausserhalb eines SELECT-Blocks!), oder Sie haben
		sich vertippt beim schreiben des Zeichens!

F: Wo darf ich unsichtbare Kommentare setzen?
A: berall! Im Precaching-Verfahren, werden diese Kommentare entfernt.

F: Darf ich Leerzeilen im Header und vor dem ersten Marker setzen?
A: Ja, der Precacher ignoriert Leerzeilen

F: Kann ich irgendwie Sektoren schlieen?
A: Nein! Das hat auch keinen Sinn! Sie knnen einfach Sektoren visuell trennen, wenn
	Sie Leerzeilen am ende eines Sektors einfgen! Diese werden dann im Viewer "angezeigt",
	aber sind wegen ihrer "Form" nicht sichtbar!

F: Gibt es beschrnkungen bei der Gre von SELECT-Blcken oder ganzen FST-Dateien?
A: Nicht vom Viewer oder von der FST-Technik her!
	Doch ihr RAM-Speicher muss 101% bis 110% der FST-Dateigre aufnehmen knnen!
	(diese 1% bis 10% sind Daten wir Marker, Schriften etc) (Durchschnittswerte!)


6. Bekannte Bugs

In der Version 2.0 kam ein Bug auf, der aber direkt nicht reproduzierbar ist.
Zu vermeiden sind Kontstruktionen wie:
...% "...
(Formatierungs-Steuerzeichen vor wrtlicher Rede; insbes. das Formatierung-Zurrcksetzen-
Zeichen!)

Fr den Fall, dass der Bug auftritt, einfach einen Zeilenumbruch an der betroffenen Stelle
machen, dann wird dieser behoben.

Ein Bugfix ist in Arbeit.


7. Versions-Geschichte

V1.0
- Verwendet nur V1.0 der FST-Technik
- Basis Technik implementiert:
-- SELECT-Statements
-- FST-Header
-- TITLE-Statement
-- $$-Labels

V2.0
- Verwendet V1.0 und V2.0 der FST-Technik
- Eigene Formatierung mit $ und % implementiert
- Header um eigene Schriften erweitert (<UFONT>)
- Header um Formatierungssteuerung f. wrtl. Rede und Kommentare erweitert (<CONTROLS>)

V2.1
- Anzeige Bug behoben, dass beim Laden und Resizen des Fensters, der Inhalt korrekt
dargestellt wird.

V2.2
- Bug behoben, wenn ein Text direkt, ohne Format oder Titel-Text beginnt,
dass der Text nicht sichtbar ist.

V3.0
- Verwendet V1.0 bis V3.0 der FST-Technik
- Bercksichtigt FST-Skript-Befehle


8. Copyright

(C) 2005 Andreas Haas (Dragon-Shape Software & Entertainment (www.dragon-shape.de))

Kontakt: info@dragon-shape.de